|
PATH Mac OS 8 and 9 Developer Documentation
> Human Interface Toolbox
> Window Manager
>
|
Mac OS 8 Window Manager Reference
|
|
|
|
PATHMac OS 8 and 9 Developer Documentation
> Human Interface Toolbox
> Window Manager
>
|
|
Mac OS 8 Window Manager Reference
|
The following Window Manager application-defined function is changed with Appearance Manager 1.0:
Application-defined window definition functions are changed with Appearance Manager 1.0 to support collapse boxes and feature reporting. See Window Definition Message Constants and Reporting the Region of a Mouse-Down Event for descriptions of these changes.
A window definition function determines how a window looks and behaves. Various Window Manager functions call a window definition function whenever they need to perform a window-dependent action, such as drawing the window on the screen. If you wish to define new, nonstandard windows for your application, you must write a window definition function and store it in a resource file as a resource of type 'WDEF'.
The Window Manager calls the Resource Manager to access your window definition function with the given resource ID; see Window Definition IDs for a description of how window definition IDs are derived from resource IDs and variation codes. You can define your own window variation codes so that you can use one 'WDEF' resource to handle several variations of the same general window.
The Resource Manager reads your window definition function into memory and returns a handle to it. The Window Manager stores this handle in the windowDefProc field of the window structure. Later, when it needs to perform an action on the window, the Window Manager calls the window definition function and passes it the variation code as a parameter.
Your window definition function is responsible for
The Window Manager declares the type for an application-defined window definition function as follows:
typedef pascal long (*WindowDefProcPtr)(
short varCode,
WindowPtr theWindow,
short message,
long param);
The Window Manager defines the data type WindowDefUPP to identify the universal procedure pointer for this application-defined function:
typedef UniversalProcPtr WindowDefUPP;
You typically use the NewWindowDefProc macro like this:
WindowDefUPP myWindowDefUPP;
myWindowDefUPP = NewWindowDefProc(MyWindow);
You typically use the CallWindowDefProc macro like this:
CallWindowDefProc(myWindowDefUPP, varCode, theWindow, message, param);
Here's how to declare the function MyWindowDefProc :
pascal long MyWindowDef(
short varCode,
WindowPtr theWindow,
short message,
long param);
The Window Manager passes a value defined by one of these constants in the message parameter of your window definition function to specify the action your function must perform. Other messages are reserved for internal use by the system.
enum {
wDraw = 0,
wHit = 1,
wCalcRgns = 2,
wNew = 3,
wDispose = 4,
wGrow = 5,
wDrawGIcon = 6,
kWindowMsgGetFeatures = 7,
kWindowMsgGetRegion = 8
};
When the Window Manager passes wDraw in the message parameter, your window definition function should respond by drawing the window frame in the current graphics port (which is the Window Manager port). The window part code to be drawn will be passed in the param parameter of your window definition function.
Your window definition function should perform the following steps:
You must make certain checks to determine exactly how to draw the frame. If the value of the visible field in the window structure is false , you should do nothing; otherwise, you should examine the param parameter and the status flags in the window structure:
You need to maintain your own state flag to determine whether the close, zoom, or collapse box is to be drawn as highlighted. Typically, you clear this state flag whenever you draw the entire frame, and you set it before drawing whenever your application is called to draw just the close, zoom, or collapse box. If the flag is set, you draw the box in a highlighted state.
The window frame typically, but not necessarily, includes the window's title, which should be displayed in the system font and system font size. The Window Manager port is already set to use the system font and system font size.
Your window definition function should return 0 as the function result for this message.
When the Window Manager passes wHit in the message parameter, your window definition function should respond by reporting the region of the specified mouse-down event. The mouse location (in global coordinates) of the window frame will be passed into the param parameter of your window definition function. The vertical coordinate is in the high-order word of the parameter, and the horizontal coordinate is in the low-order word.
In response to the wHit message, your window definition function should return one of the following constants:
enum {
wNoHit = 0,
wInContent = 1,
wInDrag = 2,
wInGrow = 3,
wInGoAway = 4,
wInZoomIn = 5,
wInZoomOut = 6,
wInCollapseBox = 9
};
Return the constants wInGrow , wInGoAway , wInZoomIn , wInZoomOut , and wInCollapseBox only if the window is active--by convention, the size box, close box, zoom box, and collapse box aren't drawn if the window is inactive. In an inactive document window, for example, a mouse-down event in the part of the title bar that would contain the close box if the window were active is reported as wInDrag.
When the Window Manager passes wCalcRgns in the message parameter, your window definition function should respond by calculating the window's structure and content regions based on the current graphics port's port rectangle. These regions, whose handles are in the strucRgn and contRgn fields of the window structure, are in global coordinates. The Window Manager requests this operation only if the window is visible. The mouse location (in global coordinates) of the window frame will be passed into the param parameter of your window definition function.
Your window definition function should call IsWindowCollapsed to determine its collapse state. Then your window definition function can modify its structure and content regions as appropriate. Typically, a window's content region is empty in a collapsed state.
Your window definition function should return 0 as the function result for this message.
When the Window Manager passes wNew in the message parameter, your window definition function should respond by performing any initialization that it may require. If the content region has an unusual shape, for example, you might allocate memory for the region and store the region handle in the dataHandle field of the window structure. The initialization function for a standard document window creates the wStateData structure for storing zooming data.
Your window definition function should ignore the param parameter and return 0 as the function result for this message.
When the Window Manager passes wDispose in the message parameter, your window definition function should respond by performing any additional tasks necessary for disposing of a window. You might, for example, release memory that was allocated by the initialization function. The dispose function for a standard document window disposes of the wStateData structure.
Your window definition function should ignore the param parameter and return 0 as the function result for this message.
When the Window Manager passes wGrow in the message parameter, your window definition function should respond to being resized by drawing a dotted outline of the window in the current graphics port in the pen pattern and mode. (The pen pattern and mode are set up--as gray and notPatXor --to conform to Appearance-compliant human interface guidelines.)
A rectangle (in global coordinates) whose upper-left corner is aligned with the port rectangle of the window's graphics port is passed into the param parameter of your window definition function. Your grow image should be sized appropriately for the specified rectangle. As the user drags the mouse, the Window Manager sends repeated wGrow messages, so that you can change your grow image to match the changing mouse location.
DrawGrowIcon draws a dotted (gray) outline of the window and also the lines delimiting the title bar, size box, and scroll bar areas.
Your window definition function should return 0 as the function result for this message.
When the Window Manager passes wDrawGIcon in the message parameter, your window definition function should respond by drawing the size box in the content region if the window is active. If the window is inactive, your window definition function should draw whatever is appropriate to show that the window cannot currently be sized. Your window definition function may also draw scroll bar delimiter lines. Your window definition function should ignore the param parameter.
If the size box is located in the window frame, draw the size box in response to a wDraw message, not a wDrawGIcon message.
Your window definition function should return 0 as the function result for this message.
When the Window Manager passes kWindowMsgGetFeatures in the message parameter, your window definition function should respond by setting the param parameter to reflect the features that your window supports. The value passed back in the param parameter should be comprised of one or more of the following values:
enum{
kWindowCanGrow = (1 << 0),
kWindowCanZoom = (1 << 1),
kWindowCanCollapse = (1 << 2),
kWindowIsModal = (1 << 3),
kWindowCanGetWindowRegion = (1 << 4),
kWindowIsAlert = (1 << 5),
kWindowHasTitleBar = (1 << 6),
};
Your window definition function should return 1 as the function result for this message.
When the Window Manager passes kWindowMsgGetRegion in the message parameter, your window definition function should respond by returning the location (in global coordinates) of the specified window region. A pointer to a window region structure will be passed in the param parameter.
The window region structure is a structure of type GetWindowRegionRec.
struct GetWindowRegionRec {
RgnHandle winRgn;
WindowRegionCode regionCode;
};
typedef struct GetWindowRegionRec GetWindowRegionRec;
typedef GetWindowRegionRec *GetWindowRegionPtr;
Your window definition function should return an operating system status ( OSStatus ) message as the function result for this message. The result code errWindowRgnInvalid indicates that the window region passed in was not valid.